Chapter 3 Calls to the Protocol Converter 



This chapter is about the Protocol Converter, which is a set of 
assembly-language routines used to support external 1/0 devices, such as 
UniDisk 3.5. To ProDOS and Pascal 1.3, the Protocol Converter appears to be 
a block device. 

The following topics are discussed in this chapter: 

□ How to locate the Protocol Converter 

□ How to issue a call to the Protocol Converter 

□ The use of each call 

□ The parameters required for each call 

□ Possible errors codes returned for each call 
n The possible causes of the errors 

At the end of this chapter is an example of an assembly-language program 
that uses a Protocol Converter call. 



Locating the Protocol Converter 

The code for the Protocol Converter always begins at address $C500 in the 
Apple lie with 32K ROM. To ensure compatibility of your programs with the 
Apple lie, however, your Protocol Converter routines should always begin 
with a search for the Protocol Converter by looking for the following bytes: 
CNOl = $20, CN03 = $00, CN05 - $03, and $CN07 = 00, where N can be 
from 1 to 7. The Protocol Converter entry point is then at address 
$CNOO + ($CNFF) + 3. The sample program at the end of this chapter 
illustrates such a search. 



How to Issue a Call to the Protocol Converter 

Protocol Converter calls are coded in a manner similar to ProDOS Machine 
MLI calls: see theProDos Technical Language Interface (MLl) calls: The program executes a JSR Qump to 
Reference Manual, Chapter 4. subroutine) to a dispatch routine at address $C500 + ($C5FF) + 3, where 

($C5FF) refers to the value of the byte located at $C5FF. 



The number of the Protocol Converter call and a two-byte pointer to the 
call's parameter list must immediately Mow the call. Here is an example of 
a call to the Protocol Converter: 



IWMCALL JSR DISPATCH ;Cali PC command dispatcher 

DFB CMDNUM ;This spe-cifies the command type 

DW CMDLIST ;2-byte (low, high) pointer to parameter list 

BCS ERROR ;Carry is set on an error 



The command number determines the Protocol Converter call to be used. 
The length and contents of the parameter list depend on the call, as 
described in Section "Descriptions of the Protocol Converter Calls." 

Upon completion of the call, the program resumes execution at the 
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DFB and DW statements are skipped, and execution resumes with the BCS 
statement. If the call is successful, the C flag (in the Processor Status 
register of the 65C02 microprocessor) is cleared (0), and the accumulator 
(the A register) is cleared to all zeros. If the call is unsuccessful, the C flag is 
set (1), and the error code is placed in the A register. After the Protocol 
Converter call, the contents of the 65C02's registers are as follows: 

Register: Processor Status X Y A PC S 

Bit: N Z C D V I B 

Successful call: xxOOxuu x x JSR+3 u 
Unsuccessful 

call: xxlOxuu x x Error JSR+3 u 

X = undefined, except in cases where index informaUon is returned in X and Y 
u = unchanged 



Most Protocol Converter calls include a two-byte pointer to a parameter list, 
which may contain information to be used by the call, or provide space for 
information to be returned by the call. 



Cautions 



You must observe the following cautions when using the Protocol 
Converter, or your program will crash: 

□ The Protocol Converter requires up to 35 bytes of stack space. Be sure 
you take this into account when calculating the stack space used by your 
program. 

Failure to allow for the stack space used by the Protocol Converter can 
result in a stack overflow, causing your program to crash when it 
attempts to access the data that have been overwritten. 

□ Data cannot be read from the Protocol Converter into RAM that is not 
both read-enabled and w rite-enabled. The Protocol Converter must be 

Reading and writing to RAM: see Section able to read from the RAM after writing to it, to obtain a checksum. 
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Reference Manual. 



a Do not attempt to use the Protocol Converter to put anything into zero 
page locations. These locations are reserved for temporary storage of 
data by the Protocol Converter. 



Descriptions of the Protocol Converter Calls 

Calls to the Protocol Converter are used 

□ to obtain status information about a device 

□ to reset a device 

□ to format the medium in a device 

□ to read from a device 

□ to write to a device 

□ to send control information to a device. 



The Protocol Converter calls, in command-number sequence, are: 



STATUS ($00) 



WRITE BLOCK ($02) 



FORMAT ($03) 



CONTROL ($04) 



INIT ($05) 



OPEN ($06) 



CLOSE ($07) 



Returns status information about a 
particular device, including general 
status (character or block device, 
read or write protection, format 
allowed, device on line); the device 
control block (set with the 
CONTROL call); the device newline 
status (character devices only); and 
device-specific information (number 
of blocks, ID string, device name, 
device type, device firmw^are 
version). 

Reads one 512-byte block from a 
disk device, and writes it to 
memory. 

Writes one 512-byte block from 
memory to a disk device. 

Prepares all blocks on a block 
device for reading and writing. 

Controls some device functions, 
including warm resets, setting the 
device control block (which controls 
global aspects of the device's 
operating environment), setting 
newline status (character devices 
only), and device interrupts. Several 
CONTROL calls are device-specific. 

Resets all resident devices. A global 
reset is done automatically on 
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keyboard; an application should 
never have to reset all devices. 

Prepares a character device for 
reading or writing. 

Tells a character device that a 
sequence of reads or writes is over. 




READ ($08) 
WRITE ($09) 



Reads a specified number of bytes 
from a specified device. 

Writes a specified number of bytes 
from memory to a specified device. 



Format of Call Descriptions 

The following sections describe each protocol converter call, including the 
command number, the parameter list, and error codes. The calls are 
discussed in command-number order. Each call is shown in this format: 

Command Name The name used to identify the call for descriptive 
purposes. 

Command Number The number, in hexadecimal, that specifies the call 
to the Protocol Converter. 

Parameter List A list of the parameters required for the call. 
General Description The purpose and use of the call. 

Parameter Descriptions A description of each parameter, and 
descriptions of data bytes pointed to by parameters. When a parameter is a 
status or control code, the meaning of each code number is discussed. 

Possible Errors A list of the error codes that can be returned by this call. 
A complete list of Protocol Converter error codes is included at the end of 
this chapter. 



STATUS 



Command Number $00 

Parameter List $03 (parameter count) 

Unit number 

Status list pointer (low byte, high 
byte) 

Status code 

The STATUS call returns status information about a particular device. The 
type of information returned is determined by the status-code parameter, 
and the location to which it is returned is determined by the status list 

After a STATUS call has been executed, the 65C02's X and Y registers 
contain the number of bytes of status information returned (the low byte of 
this number is in the X register, and the high byte is in the Y register). 



Parameter Descriptions 



Parameter 3 for this call. 

Count 

1-byte value 

Unit Number The Protocol Converter assigns each device a unique 

1- byte value number during initialization (on startup and cold 

reset). The numbers are in the range $01— $7E, and 
are assigned according to the devices' positions in the 
chain. 

Use a unit number of $00 and a status code of $00 in a STATUS call to 
obtain the status of the Protocol Converter itself (see the discussion under 
Status Code = $00, below). 

Status List Points to the buffer to which the status is to be 

Pointer returned. The length required for the buffer varies 

2- byte value depending on the status request being made. 



Status Code Indicates what kind of status request is being made. 
1-byte value Status codes are in the range $00-$FF, as follows: 



Table 3-1. Status Codes 



Code Status Returned 

$00 Return device status 

$01 Return device control block (DCB) 

$02 Return newline status (character devices only) 

$03 Return device information block (DIB) 

$05 Return UniDisk 3.5 status 



Status codes $01 and $02 are not supported by the UniDisk 3.5 and result 
in an error (BADCTL $21). Device status for the UniDisk 3.5 can be 
obtained by using status code $05. 

Status Code = $00, Return Device Status The device status consists of 
four bytes. The first is the general status byte: 



Bit 


Description 


7 


= character device. 1 = block device 


6 


1 = write allowed 


5 


1 =^ read allowed 


4 


1 = device on line or disk in drive 


3 


= format allowed 


9 


= medium write protected (block devices only) 


1 


1 = device currently interrupting 





1 - device currently open (character devices only) 



If the STATUS call is for a block device, the next three bytes (low byte 
first) are the size in 512-byte blocks. The maximum size is 16 million 
(SFFFFFF) blocks (about 8 gigabytes). If the call is for a character device, 
these three bytes must be set to zero. 

Unit Number $00: A STATUS call with status code = $00 and unit 
number = $00 returns the status of the Protocol Converter itself. In this 
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STAT_LIST 



DFB 
DFB 
DFB 
DFB 
DFB 
DFB 
DFB 
DFB 



Number-Devices 
Interrupt-Status 



Devices hooked to PC 

Bit 6 clear = interrupt 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 



sent 



The Number_Devices byte returns the total number of intelhgent devices 
attached to the Protocol Converter. The Interrupt_Status byte is a copy of 
the Asynchronous Communications Interface Adapter (ACIA) status 
register at the time of the interrupt, and is used to indicate that a device 
requires interrupt servicing. If the sixth bit of this byte equals zero, one or 
more devices in the Protocol Converter Bus daisy chain must be serviced; 
your interrupt handler must poll each device on the chain to determine 
which ones. 

About Interrupts: Devices that require interrupt servicing must use the 
EXTINT line on the external disk port connector of the Apple lie to be 
supported by the Protocol Converter. UniDisk 3.5, for example, does not 
support this line, and so cannot generate interrupts to the Protocol 
Converter. See Section "CONTROL" for instructions on enabling Protocol 
Converter interrupts. See Appendix E in the Apple lie Reference 
MoMUoJ. for more inform.ation about program.m.ing with interrupts. 

Status Code = SOI, Return Device Control Block The device control 
block (DCB) is used to control various operating characteristics of a device, 
and is device dependent. Each device has a default DCB, which can be 
altered with a CONTROL call. The first byte (the count byte) gives the 
number of bytes in the control block (not including the count byte), so the 
length never exceeds 256 bytes (257 including the count byte). 

UniDisk 3.5 has no DCB, and returns an error (BADCTL $21) in response 
to this call. 

Newiine read mode: see Chapter 4 in the Status Code = SO^, Return NewHne Status Newline status applies only 
PRODOS Tech nical Reference Manual. to character devices. Use of statcode = $02 with a block device results in 

error BADCTL ($21). 

Status Code = $03, Return Device Information Block The device's 
information block contains information identifying the device, its type, and 
various other attributes. The returned status hst has the following form: 



ACIA status register: see Section 
"Firmware Handling of Interrupts" in the 

Apple lie Reference Manual. 



STAT_LIST DFB Devi ce_S t a t by t e 1 

DFB Device_Si ze_Lo 

DFB Device_Si ze_Med 

DFB Device_Si2e_Hx 

DFB ID_St ring-Length 

ASC ' <devi ce name> ' 

DFB Device_Type_Code 

DFB Device-Subtype_Co 

DW Version 



;Same as byte 1 in Status Code-0 
jNumber of blocks (block device) 
;Number of blocks Cmiddle byte) 
;Number of blocks (high byte) 
;Length in bytes (16 max.) 
;7-bit ASCII, uppercase, padded 

with spaces, eighth bit always«0 

(16 bytes) 

de 

jDevice firmware version number 



Status Code = $05, Return UniDisk 3.5 Status This call allows the 
diagnostic program to get more detailed information about the cause of a 
read or write error, and to examine the contents of the 65C02's registers 
after a CONTROL Protocol Converter call with control code = $05 (see 
Section "CONTROL"). The returned status list has this form: 



STAT_LIST 



DFB 
DFB 
DFB 
DFB 
DFB 
DFB 
DFB 
DFB 



$00 

Error 

Retries 

$00 

A_Value 
X_Value 
Y_Value 
P_Value 



;Soft Error byte (see below) 
;Number of retries (see below) 



Acc value after a CONTROL EXECUTE call 
X value after EXECUTE 
Y value after EXECUTE 

Processor Status value after EXECUTE 
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UniDisk 3.5 Status) contains the following bits: 



Bit Description 

7 

6 

5 1 = address field mark or checksum error 

4 1 data field checksum error 

3 1 = data field bitslip mark mismatch 

2 1 = seek error; unexpected track value found 

in address field 

1 





The Retries byte returned by a STATUS call with status code = $05 (Return 
UniDisk 3.5 Status) specfies the number of address fields that had to be 
passed before the operation was completed. This information could be used, 
for example, to determine the number of passes necessary to read a data 
field correctly: If Retries is found to be greater than the number of sectors 
on the target track, then more than one pass was required. 

The last four bytes of the status list are set only after a CONTROL call with 
control code = $05, and are zero after any other call (STATUS calls do not 
clear the status bytes). 




Possible Errors 

The following errors can be returned by the STATUS call: 

$01 BADCMD An unimplemented command was issued 

$04 BADPCNT Bad call parameter count 

$06 BUSERR Communications error 

$2 1 BADCTL Invalid status code 

$30-$3F Device-specific errors 



READ BLOCK 



v7 



Command Number $01 

Parameter List $03 (parameter count) 

Unit number 

Data buffer (low byte, high byte) 

Block number (low byte, mid byte, 
high byte) 

The READ BLOCK call reads one 512-byte block from the disk device 
specified by the unit-number parameter into memory starting at the address 
specified by the data-buffer parameter. 



Parameter Descriptions 



Parameter 
Count 

1-byte value 

Unit Number 

1-bvte value 



3 for this call. 



Data Buffer 

2-byte value 



'd-oyie vame 



The Protocol Converter assigns each device a unique 
number during initialization (on startup and cold 
reset). The numbers are in the range $01— $7E, and 
are assigned according to the devices' positions in the 
chain. A unit number of $00 in the STATUS call 
returns the number of devices connected to the 
Protocol Converter. 

Points to the buffer into which the data is read. The 
buffer must be 512 or more bytes in length. 



Block Number The logical address of a block of data to be read. There 

is no general connection between block numbers and 
the layout of tracks and sectors on the disk. The 
translation from logical to physical blocks is 
performed by the device. (The most significant byte is 
zero for all devices currently in use.) 



Possible Errors 



The following errors can be returned by the READ BLOCK call: 



$01 


BADCMD 


An unimplemented command was issued 


$04 


BADPCNT 


Bad call parameter count 


$06 


BUSERR 


Communications error 


$27 


lOERROR 


1 /O error 


$28 


NODRIVE 


No device connected 


$2D 


BADBLOCK 


Invalid block number 


$2F 


OFFLINE 


Device off-line or no disk in drive 



^ 

I \ 



WRITE BLOCK 



Command Number $02 

Parameter List $03 (parameter count) 

Unit number 

Data buffer (low byte, high byte) 

Block number (low byte, mid byte, 
high byte) 

The WRITE BLOCK call writes one 512-byte block from memory to the disk 
device specified by the unit-number parameter. The block in memory starts 
at the address specified by the data-buffer parameter. 



Parameter Descriptions 



Parameter 
Count 

1-byte value 

Unit Number 

1-byte value 



3 for this call. 



Data Buffer 

2-byte value 

Block Number 
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The Protocol Converter assigns each device a unique 
number during initialization (on startup and cold 
reset). The numbers are in the range $01— $7E, and 
are assigned according to the devices' positions in the 
chain. A unit number of $00 in the STATUS call 
returns the number of devices connected to the 
Protocol Converter. 

Points to the buffer from which the data is to be 
written. 

The logical address of a block of data to be written, 
i nerc i^i uv gciterdi cunnecuun ueiwcen uioctv 
numbers and the layout of tracks and sectors on the 
disk. The translation from logical to physical blocks is 
performed by the device. (The most significant byte is 
zero for all devices currently in use.) 



I I 



Possible Errors 

The following errors can be returned by the WRITE BLOCK call: 
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$04 


BADPCNT 


Bad call parameter count 


$06 


BUSERR 


Communications error 


$27 


lOERROR 


1/0 error 


$28 


NODRIVE 


No device connected 


$2B 


NOWRITE 


Disk write protected 


$2D 


BADBLOCK 


Invalid block number 


$2F 


OFFLINE 


Device off-Une or no disk in drive 



I 



FORMAT 



Command Number $03 

Parameter List $01 (parameter count) 

Unit number 

The FORMAT call prepares all blocks on the recording medium of a block 
device for reading and writing. The formatting done by this call is not linked 
to any operating system; for example, bitmaps and catalogs are not written 
by this call. 



Parameter Deschotions 

■ 

Parameter 1 for this call. 

Count 

1-byte value 

Unit Number The Protocol Converter assigns each device a unique 
1-byte value number during initialization (on startup and cold 

reset). The numbers are in the range $01— $7E, and 
are assigned according to the devices' positions in the 
chain. A unit number of $00 in the STATUS call 
returns the number of devices connected to the 
Protocol Converter. 



Possible Errors 

The following errors can be returned by the FORMAT call: 



$01 


BADCMD 


An unimplemented command was issued 


$04 


BADPCNT 


Bad call parameter count 


$06 


BUSERR 


Communications error 


$27 


lOERROR 


I /O error 


$28 


NODRIVE 


No device connected 


$2B 


NOWRITE 


Disl^ write protected 


$2F 


OFFLINE 


Device off-line or no disl^ in drive 



CONTROL 




Command Number $04 

Parameter List $03 (parameter count) 

Unit number 

Control list (low byte, high byte) 
Control code 

The CONTROL call sends control information to the device. The 
information can be of a general nature (such as resets or interrupts), or 
device-specific (such as Download to UniDisk 3.5 RAM). 

A CONTROL call to unit number $00 sends control information to the 
Protocol Converter itself. See the discussions under Control Code = $00 
and Control Code = $01, below. 



Parameter Descriptions 



Parameter 
Count 

1-byte value 

Unit Number 

1-byte value 



3 for this call. 



Control List 

2-byte value 



The Protocol Converter assigns each device a unique 
number during initialization (on startup and cold 
reset). The numbers are in the range $01— $7E, and 
are assigned according to the devices' positions in the 
chain. A unit number of $00 in the STATUS call 
returns the number of devices connected to the 
Protocol Converter. Use a unit number of $00 in the 
CONTROL call to send control information to the 
Protocol Converter itself. 

Points to the buffer from which the control 
information is read. The first two bytes (the count 
bytes, low byte first) of the control list specify the 
number of bytes in the list (not including the count 
bytes); the remainder of the list contains the control 
information passed to the device. 




Every CONTROL call must have a control list; if no control information 
being passed, then the control hst consists of the count bytes only: 

CTRL.LIST DW $00 



Control Code The number of the control request being made. 

1-byte value Control codes are in the range $00— $FF. The 

following requests are not device-specific: 

Code Control Function 

$00 Reset the device 

$01 Set device control block (DOB) 

$02 Set newline status (character devices only) 

$03 Service device interrupt 

Control requests to unit number $00 are sent to the Protocol Converter 
itself: 

Code Control Function 

$00 Enable interrupts from Protocol Converter 

$01 Disable interrupts from Protocol Converter 

Specific devices may respond to some or all of these additional control 

requests: 

Code Control Function 

$04 Eject disk 

$05 Run a 65C02 subroutine 

$06 Set download address 

$07 Download to device RAM 



Control Code = $00, Reset the Device Performs a warm reset of the 
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control hst for this call is device dependent. 
The control list for this call for UniDisk 3.5 devices is: 

CTRI — LIST DW $00 ;No parameters are passed 



Unit Number $00: A CONTROL call with control code = $00 and unit 
number = $00 enables interrupts from the Protocol Converter. This call 
informs the firmware that external interrupts are possible, and directs it 
to call the user's interrupt handler if an interrupt occurs. It also turns on 
the Asynchronous Communications Interface Adapter (ACIA) for port 1. 

When the user's interrupt handler identifies an external interrupt, you 
can determine if it came from the Protocol Converter by making a 
STATUS call with unit number = $00 and control code = $00 (see 
Section "STATUS"). See Appendix E in ih^ Apple Ik Reference Manual 
for more information on handling interrupts. 

Control Code = $01, Set Device Control Block Alters the contents of 
the device control block (DOR), The OCR is usually used to set global 
aspects of a device's operating environment. Each device has a default 
<;pttin^ for the DCR. set on initialization. Since the length of the DCR is 
device dependent, you should first read in the DCR with the STATUS call, 
then alter the bits of interest, and finally, use the same byte string as the 
control block for the CONTROL call. The first byte (the count byte) of the 
DCR gives the number of bytes in the control block {not including the count 
byte), so the length never exceeds 257 bytes, including the count byte. 

UniDisk 3.5 has no DCR; a Set DCR CONTROL call to UniDisk 3.5 returns 
an error (RADCTL $21). 

Unit Number = $00: A CONTROL call with control code = $01 and unit 
number = $00 disables interrupts from the Protocol Converter. This call 
turns off the ACIA for port 1 and sets the least significant bit of the ACIA 
control register to zero. 

Control Code = $02, Set Newline Status Sets a character device to 
newdine enabled or newline disabled. 

Control Code = $03, Device Service Interrupt To be used as needed 
for interrupt-driven devices. 

Control Code = $04, Eject Disk To be used for devices that support an 
auto-eject feature. 

Causes UniDisk 3.5 to auto-eject a disk. There are no parameters in the 
control list, and no errors are returned if the disk ejected correctly or 
there was no disk in the drive. Error code $27 (I/O error) is returned if 
the eject failed, that is, a disk is still in the drive. The control list for 
UniDisk 3.5 is: 



CTRL-LIST DN $00 ;No parameters are passed 



Possible Errors 

The following errors can be returned by the CONTROL call: 



$01 


BADCMD 


An unimplemented command was issued 


$04 


BADPCNT 


Bad call parameter count 


$06 


BUSERR 


Communications error 


$21 


BADCTL 


Invalid control code 


$22 


BADCTLPARM 


Invalid parameter list 


$30-$3F 




Device-specific errors 



INIT 



The INIT call resets all intelligent devices attached to the Protocol 
Converter. The Protocol Converter goes through an initialization sequence, 
cold-resetting all devices and sending each its unit number. This call is 
made automatically on startup; an application should never have to make 

this call. 



Parameter Descriptions 



Command Number 



$05 



Parameter List 



$01 (parameter count) 
$00 (unit number) 



Parameter 
Count 

1-bvte value 



1 for this call. 



Unit Number 

1-byte value 



The unit number used in this call is always $00. 



Possible Errors 



The following errors can be returned by the INIT call: 

$01 BADCMD An unimplemented command was issued 

$04 BADPCNT Bad call parameter count 

$06 BUSERR Communications error 

$28 NODRIVE No device connected 



OPEN 



Command Number $06 

Parameter List $01 (parameter count) 

Unit number 

The OPEN call prepares a character device for reading or writing. 

Since UniDisk 3.5 is a block device, it does not accept this call. An 

attempt to use an OPEN call with UniDisk 3.5 will result in an error 
(BADCMD $01). 



Karameter Descriptions 



Parameter 1 for this call. 

Count 

1 -byte value 

Unit Number The Protocol Converter assigns each device a unique 
1-byte value number during initialization (on startup and cold 

reset). The numbers are in the range $01— $7E, and 
are assigned according to the devices' positions in the 
chain. A unit number of $00 in the STATUS call 
returns the number of devices connected to the 
Protocol Converter. 



Possible Errors 

The following errors can be returned by the OPEN call: 



$01 


BADCMD 


An unimplemented command was issued 


$04 


BADPCNT 


Bad call parameter count 


$06 


BUSERR 


Communications error 


$28 


NODRIVE 


No device connected 


$2F 


OFFLINE 


Device off-line or no disk in drive 



CLOSE 



^2 = 



Command Number 
Parameter List 



$07 

$01 (parameter count) 
Unit number 



The CLOSE call tells a character device that a sequence of reads or writes is 



over. 



Since UniDisk 3.5 is a block device, it does not accept this call. An 
attempt to use a CLOSE call with UniDisk 3.5 will result in an error 
(RADCMDSOl). 



Parameter Descriptions 



Parameter 
Count 

1-byte value 

Unit Number 

1-byte value 



1 for this call. 



The Protocol Converter assigns each device a unique 
number during initialization (on startup and cold 
reset). The numbers are in the range $01— $7E, and 
are assigned according to the devices' positions in the 
chain. A unit number of $00 in the STATUS call 
returns the number of devices connected to the 
Protocol Converter. 



Possible Errors 

The following errors can be returned by the CLOSE call: 



$01 


BADCMD 


An unimplemented command was issued 


$04 


BADPCNT 


Bad call parameter count 


$06 


BUSERR 


Communications error 


$28 


NODRIVE 


No device connected 


$2F 


OFFLINE 


Device off-line or no disk in drive 



i 



READ 
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Command Number $08 

Parameter List $04 (parameter count) 

Unit number 

Buffer pointer (low byte, high byte) 

Byte count (low byte, high byte) 

Address pointer (low byte, mid byte, 
high byte) 

The READ call reads the number of bytes specified by the byte-count 
parameter into memory starting at the address specified by the 
buffer-pointer parameter. 

Macintosh: This call can be used by UniDisk 3.5 devices to read 
524-byte data blocks written by an Apple Macintosh™ Computer. 



Parameter Descriptions 



Parameter 
Count 

1-byte value 

Unit Number 

1-byte value 



4 for this call. 



Buffer Pointer 

2-byte value 



Byte Count 

2-byte value 



The Protocol Converter assigns each device a unique 
number during initiahzation (on startup and cold 
reset). The numbers are in the range $01— $7E, and 
are assigned according to the devices' positions in the 
chain. A unit number of $00 in the STATUS call 
returns the number of devices connected to the 
Protocol Converter. 

Points to the buffer into which the data is read. The 
buffer must be large enough to contain the number of 
bytes requested by the byte-count parameter. 

Specifies the number of bytes to be transferred. 



Macintosh: The byte count used to read Macintosh disks with a 
UniDisk 3.5 is always 524 bytes ($020C). 

Address Specifies the address to start reading from. The 

Pointer meaning of this parameter depends on the device 

3-byte value being read. 

Macintosh: When using a UniDisk 3.5 to read Macintosh disks, the 
address pointer specifies the number of the 524-byte Macintosh block to 
be read (from $00 to $03 IF for a single-sided disk). 



Possible Errors 

The following errors can be returned by the READ call: 



$01 


BADCMD 


An uniiiipiemeriied comifiaud was issued 


$04 


BADPCNT 


Bad call parameter count 


$06 


BUSERR 


Communications error 


$27 


lOERROR 


I/O error 


$28 


NODRIVE 


No device connected 


$2D 


BADBLOCK 


Invalid block number 


$2F 


OFFLINE 


Device off-line or no disk in drive 



WRITE 




L H 1 T^" 



Command Number $09 

Parameter List $04 (parameter count) 

Unit number 

Buffer pointer (low byte, high byte) 

Byte count (low byte, high byte) 

Address pointer (low byte, mid byte, 
high byte) 

The WRITE call writes the number of bytes specified by the byte-count 

parameter to the specified unit from memory starting at the address 

indicated by the buffer-pointer parameLer. The meaning of the address 

pointer depends on the type of device (see the parameter descriptions, 
below). 

Macintosh: This call can be used by UniDisk 3.5 devices to write 
524-byte blocks for use by an Apple Macintosh computer. 



Parameter Descriptions 



Parameter 
Count 

1-byte value 

Unit Number 

1-byte value 



4 for this call. 



Buffer Pointer 

2-byte value 

Byte Count 

2-byte value 



The Protocol Converter assigns each device a unique 
number during initialization (on startup and cold 
reset). The numbers are in the range $01— $7E, and 
are assigned according to the devices' positions in the 
chain. A unit number of $00 in the STATUS call 
returns the number of devices connected to the 
Protocol Converter. 

Points to the buffer from which the data is to be 
written. 

Specifies the number of bytes to be transferred. 




Macintosh: The byte count used to write Macintosh disks with a 
UniDisk 3.5 is always 524 bytes ($020C). 

Address Specifies the address to start wTiting from. The 

Pointer meaning of this parameter depends on the device 

3-byte value being written to. 

Macintosh: When using a UniDisk 3.5 to wTite Macintosh disks, the 
address pointer specifies the number of the 524-byt.e Macintosh block to 
be wTitten (from SOO to S031F for a single-sided disk). 



Possible Errors 

The following errors can be returned by the WRITE call: 





BADCMD 


An uniiTiDlemented command was issued 

J. 


$04 


BADPCNT 


Bad call parameter count 


$06 


BUSERR 


Communications error 


$27 


lOERROR 


I/O error 


$28 


NODRIVE 


No device connected 


$2D 


BADBLOCK 


Invalid block number 


$2F 


OFFLINE 


Device off-line or no disk in drive 



An Example: Issuing a Protocol Converter Call 



0000 
0000 
0000 
0000 
0000 
0000 

0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0300 
0300 
0300 
0300 
0300 
0300 
0303 
0305 
0305 
0305 



0006 



0007 



FDED 
FD8E 



0000 



0300 



20 
B0 



43 03 

1C 0321 



1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
1 1 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 



e lie 



Here is an example of a program that issues a STATUS call to the Protocol 
Converter to obtain information about a device. 

The code for the Protocol Converter in the Apple 11c with 32K ROM 
always begins at address $C500; however, to ensure compatibility with 
the Apple lie, your programs should always do a search for the Protocol 
Converter, as in the following example. 



« 

« 
« 

« 
* 

* 
# 

« 



This ex am pie shows how to find 
and use a PC interface. A search 
is made for a PC, and when one is 
found, a vector is set up which 
points to the PC entry. Then a 
Device Information Block STATUS call 
is made, and if successful, the name 
string embedded in the DIB is output 
to the screen. Only the first device 
in the chain is accessed. 



ZPTempL 
« 

ZPTempH 

« 

CDut 
CRQut 



Status Cmd equ 



MSB 


ON 


equ 


$0006 


equ 


$0007 


equ 


$FDED 


equ 


$FD8E 


equ 






;Temporary zero 
page storage 



; Conso 1 e output 
; Car r i age return 



org 



$300 



* Find a Protocol Converter in one of the 

* slots. 

# 



jsr 

be 5 



FindPC 
Error 



36 
37 
38 



* Now make the DIB call to the first guy 




0305 


• 20 

« ^ ftr 


67 


03 


39 




j s r 




Dispatch 


0308 


- 00 

■ ft/ ft/ 






40 




df b 




S ta t usCmd 


0309 


- 8A 


03 




4 1 




dw 




DParms 


V O V D 


• G0 


1 4 


0321 

ft/ ^ k I 


42 




b c s 

^^F 




Error 


El J V U 


w 
■ 






43 


# 








030D 








44 


* Got the 


DIB 


; now print the name string 


030D 








45 










030D 


• A2 


00 




46 




Idx 




#0 


030F 


■ 
■ 




030F 

ft/ %^ ft/ 1 


47 


morechars 


eau 




« 


030F 


■ BD 


74 


03 


48 




Ida 




DIBName , x 


031 2 


■ 09 

■ ft/ 


80 

ft/ 




49 




or a 




i*'$80 ;COut wants high 


0314 








50 


# 






Bit set 










5 1 


« 








0314 


: 20 

■ ft/ 


ED 


FD 


52 




i 5 ^ 




CQut 


031 7 


: E8 






53 




i nx 






031 8 


■ EC 


73 


03 


54 




c px 

r 




DIBNameLen 


031 B 


: 90 

ft ftf 


F2 


030F 


55 




bit 




mor echar s 


03 1 D 








56 










03 ID 


: 20 

ft V 


8E 


FD 


57 








CRDut iFinish it off 


0320 








58 


# 






with a return 


0320 








59 


# 








0320 


: 60 






60 




rts 






032 1 








61 


# 








032 1 








62 


« 








032 1 






032 1 


63 


Error 


equ 






0321 

V W b 1 








64 










032 1 








65 


* There's 


either 


no PC around, or there 


032 1 

ft/ V ^ 1 








66 


* was no 


Uni t 




... qi ve messaqe 


032 1 








67 










032 1 


: A2 







68 




Idx 




#0 


0323 

V w fc* w 






0323 


69 


e r r 1 


equ 




# 


0323 


: BD 


2F 


03 


70 




Ida 




Messaqe , x 


0326 


: F0 

ft ft/ 


06 


032E 


71 




beq 




e r r ou t 


D O ^ w 


■ 20 


ED 


FD 

1 X^ 


72 




jsr 




COut 


032B 


• E8 

ft ^ w 






73 




i nx 






032C 


■ D0 

ft V 


F5 


0323 


74 




bne 




er r 1 


032E 

ft/ V b ^ ■ 








75 


# 








032E 

ft/ W b ^ 1 






032E 


76 


e r r ou t 


equ 




« 


032E 

ft/ W ^ ^ I 


■ 60 

I ft/ 






77 

F F 




r t5 






032F 








78 


# 








032F 

U w7 C 1 


■ CE 


CF 


A0 D0 

1 1 ^# ft/ 


79 


Me 5 s aoe 


a5 c 




'NO PC QR NO DEVICE' 


034 1 ; 

ft/ V 


: 8D 


00 




80 


df b 




$8D,0 


0343 ' 








81 










0343 ' 








82 


# 








0343 ' 






0343 

ft/ W# • 


83 


FindPC 


equ 






D O t O . 








P4 


# 








0343: 








85 


* Search 


Blot 


7 


to slot 1 looking for 


0343: 








86 


* signature byt 


es 


0343: 








87 


« 








0343: 


: A2 


07 




88 




Idx 




#7 ; Do for seven 


0345: 








89 








slots 


0345: 


: A9 


C7 




90 




Ida 




#$C7 



0347 
0349 
034B 
034D 
034D 
034D 
034F 
034F 
034F 
0351 
0354 
0354 
0356 
0356 
0358 
0359 
035B 
035B 
055B 
035B 
035B 
035B 
035C 
035D 
035D 
035D 
035D 
035D 
035D 
035D 
035D 
035D 
035D 
035E 
035F 
035F 
0361 
0361 
0361 
0361 
0361 
0361 
0361 
0361 
0363 
0365 
0367 
0367 
0369 
0369 
0369 
0369 



85 
A9 
85 



B1 
D9 



C6 
CA 
D0 



38 
60 



88 
88 



07 
00 
06 



A0 07 



06 
70 



F0 07 



07 



F2 



10 EE 



A9 FF 
85 06 
A0 00 



61 06 



034D 



034F 



03 



035D 



034D 



035D 



034F 



0361 



91 
92 
93 
94 
95 
96 
97 
98 
99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
1 09 
1 10 
1 1 1 
112 
1 13 
114 
115 
1 16 
1 17 
1 18 
119 
120 
121 
122 

123 

124 

125 

126 

127 

128 

129 

130 

131 

132 

133 

134 

135 

136 

137 

138 

139 

140 

141 

142 



5 ta 
Ida 
5 t a 



ZPTempH 
#$00 

ZPTempL 



news 1 o t 



aga i n 



equ 
Idy 

equ 
Ida 
cmp 

beq 

dec 
dex 
bne 



#7 



(ZPTempL) 
s i g t ab , y 

maybe 

ZPTempH 

news lot 



y 



;One of four 
byte signature 

; F ound one 
signature byte 



If we 
f ind 



get here, it's because we couldn't 
a Protocol Converter. 



« 



Exit with the carry set. 



* 
« 
« 



sec 
rts 



If we get here, it means that one or 
more of the signature bytes 
for this card are what we're looking 
f or . Decrement the byte 
counter and branch back to 
remaining byt 



verify any 



maybe 



equ 
dey 
dey 

bpl 



all 



; If N=1 
s i g bytes 



then 
o k ay 



aga i n 



* 

* 
« 



Found a Protocol Converter interface. 

Set up the call address. 
We already have the high byte C$CN>; 

we just need the low byte. 



f oundPC 



equ 
Ida 
s t a 
Idy 

Ida 



'SFF 

ZPTempL 

#0 

CZPTempL) ,y 



; For 
indirect load 
;Get the 
byte 



« 
ft 



Now the Acc h 
entry point. 



the low order ProDOS 
The PC entry is 



0369 








143 


• three : 


Locations past this... 


0369 








144 








0369 


: 18 






145 




c 1 c 




036A 


:69 


03 




146 




adc 


#3 


036C 


:85 


06 




147 




s t a 


ZPTempL 


036E 








148 


« 






036E 








149 


* Now ZPTempL hi 


as the PC entry point. 


036E 








150 


* Return 


with < 


carry clear. 


036E 








151 








036E 


: 18 






152 




c 1 c 




036F 


:60 






153 




r ts 




0370 








154 








0370 








155 








0370 








156 


* These are the 


PC signature bytes in 


0370 








157 


* their relative order. 


0370 








158 


* The $FF 


byte: 


a are filler bytes and 


0370 








159 


* are not 


; compared. 


0370; 








160 








0370 : 


: FF 


20 


FF 00 


161 


s i q t ab 


df b 


$FF,$20,$FF,$00 


0374; 


: FF 


03 


FF 00 


162 


dfb 


$FF,$03,$FF,$00 


0378 ; 








163 


* 






0378: 








164 


* 






0378: 






0378 


165 


Dispatch 

1 


equ 


* 


0378: 


;6C 


06 


00 


166 


jmp 


(ZPTempL) ; Simulate 


037B: 








167 


♦ 




an indirect JSR to PC 


037B: 








168 








037B: 








169 


# 






037B: 






037B 


170 


DParms 


equ 




037B: 


03 






171 


DPParmCt 


dfb 


3 ; 5 1 a t u s 


037C : 








172 


# 


Cc 


ills have three parameters 


037C: 


1 






173 


DPUni t 


dfb 


1 


037D: 


80 


03 




174 


DPBuf f er 


dw 


DIB 


037F : 


03 






175 


DPStatCode 


dfb 


3 


0380 : 








176 








0380: 








177 


« 






0380 : 






0380 


178 


DIB 


equ 


« 


0380 : 


00 






179 


DIBStatByt 


el dfb 


> 


0381 : 


00 


00 


00 


180 


DIBDevSi ze 


dfb 


0,0,0 










1 P 1 

1 O 1 


DIBNameLen 


dfb 





0385: 






0010 


182 


DIBName 


ds 


16,0 


0395: 


00 






183 


DI BType 


dfb 





0396: 


00 






184 


DIBSubType 


dfb 





0397: 


00 


00 




185 


DIBVer 5 ion 


dw 





0399: 








186 


« 






0399: 








187 









£ 

. L 



■ r 



I f 



Summary of Commands and Parameters 

This is a summary of Protocol Converter calls. In each case, byte of the 
command parameter list (CMDLST) specifies the number of parameters in 
the command list (not including byte 0). Parameters that require more than 
one byte (the status list pointer, for example) are entered low byte first. The 
meaning of the address-pointer parameter is device specific. See the 
sections on the individual calls in this chapter for a discussion of each 
parameter. 



Figure 3-1. Summary of Protocol Converter Commands and Parameters 



- ■- ' r uh> I t 




WRITEBLOCK 



Block Num 



FORMAT 






$03 


$01 


$03 




Unit Num 


Unit Num 


Unit Num 


1 Buffer Ptr 




Ctl List Ptr 




Ctl Code 




Command 






Buffer Ptr 








1 Bvte Count 












1 Address Ptr 




Buffer Ptr 



Byte Count 




Unused bytes 




r ^ 



. i 



L - 



Summary of Error Codes 

mmmmmmmmmmmmmmsmimmmmmKam 

This is a summary of Protocol Converter call error codes, including a brief 
description of the possible causes for each. If there is no error, the C flag (in 
the Processor Status register of the 65C02 microprocessor) is cleared (0), 
and the accumulator (the A register) contains zeros. If the call was 
unsuccessful, the C flag is set (1), and the A register contains the error code. 



$00 
$01 



BADCMD 



$04 



BADPCNT 



$06 



BUSERR 



$11 



BADUNIT 



$21 



BADCTL 



$22 



BADCTLPARM 



$97 



lOERROR 



$28 



NODRIVE 



No error. 

A nonexistent command was issued. Check 
the command number in the Protocol 
Converter call. 

Bad call parameter count. The call 

constructed. Make sure the parameter list 
has the correct number of parameters. 

A communications error between the 
device controller and the host. Make sure 
that RAM is both read-enabled and 
write-enabled. Check the hardware (cables 
and connectors) between the device and 
the host. Check for noise sources; make 
sure the cable is properly shielded. 

Unit number $00 was used in a call other 
than STATUS, CONTROL, or INIT. 

The control or status code is not supported 
by the device. 

The control parameter list contains invalid 
information. Make sure each value is within 
the range allowed for that parameter. 

The device encountered an I/O error when 
trying to read or write to the recording 
medium. Make sure that the medium in the 
device is formatted and not defective. Make 
sure the device is operating correctly. 

The device is not connected. This can occur 
if the device is not connected but its 
controller is, or if there is no device with the 
unit number specified. 



$2B NOWRITE The medium in the device is write 

protected. 



$2D BADBLOCK The block number is outside the range 

allowed for the medium in the device. Note 
that this range depends on the type of 
device and the type of medium in the 
device (single-sided vs. double-sided disk, 
for example). 

$2F OFFLINE Device off-line or no disk in drive. Check 

the cables and connections; make sure the 
medium is present in the drive, and that the 
drive is functioning correctly. 

$30-$3F DEVSPEC Errors which differ from device to device. 

See the technical manual for the device in 
question for details. 

$40-$4F Reserved for future expansion. 

$50-$7F NONFATAL A device-specific soft error. The operation 

completed successfully, but some 
exception condition was detected. See the 
technical manual for the device in question 
for details. 



